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Introduction 



With the addition of the Networking Support Utilities, UNIX System 
V/386 Release 3.2 provides comprehensive support for networking services. 
This Primer describes STREAMS, a major building block of that support. The 
Primer provides a high-level, technical overview of STREAMS; it is intended for 
managers and developers who have prior knowledge of the UNIX System and 
of networking or other data communication facilities. For a more detailed 
description of STREAMS, see the STREAMS Programmer's Guide, 

The UNIX System was originally designed as a general-purpose, multiuser, 
interactive operating system for minicomputers. Initially developed in the 
1970's, the system's communications environment included slow to medium 
speed, as5mchronous terminal devices. The original design, the communica- 
tions environment, and hardware state of the art influenced the character 
input/output (I/O) mechanism, but the character I/O area did not require the 
same emphasis on modularity and performance as other areas of the system. 

Support for a broader range of devices, speeds, modes, and protocols has 
since been incorporated into the system, but the original character I/O 
mechanism, which processes one character at a time, made such development 
difficult. 

The current generation of networking protocols is exemplified by Open 
Systems Interconnection (OSI), Systems Network Architecture (SNA), 
Transmission Control Protocol/Internet Protocol (TCP/IP), X.25, and Xerox 
Network Systems (XNS). These protocols provide diverse functionality, lay- 
ered organization, and various feature options. When developing these proto- 
col suites, developers faced additional problems, because there were no 
relevant standard interfaces in the UNIX System. 

Attempts to compensate for the above problems have led to diverse, ad- 
hoc implementations; for example, protocol drivers are often intertwined with 
the hardware configuration in which they were developed. As a result, func- 
tionally equivalent protocol software often cannot interface with alternate 
implementations of adjacent protocol layers. Portability, adaptability, and 
reuse of software have been hindered. 

AT&T decided to enhance the character I/O area in Release 3.1. The 
result is STREAMS, a general, flexible fadlity and a set of tools for develop- 
ment of UNIX System communication services. With STREAMS, developers 
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can provide services ranging from complete networking protocol suites to indi- 
vidual device drivers. 

STREAMS defines standard interfaces for character I/O within the UNIX 
System kernel, and between the kernel and the rest of the UNIX System. The 
associated mechanism is simple and open-ended. It consists of a set of system 
calls, kernel resources, and kernel utility routines. The standard interface and 
open-ended mechanism enable modular, portable development and easy 
integration of higher-performance network services and their components. 
STREAMS does not impose any specific network architecture. Instead, it pro- 
vides a powerful framework with a consistent user interface that is compatible 
with the existing character I/O interface still available in UNIX System V. 

The modularity and design of STREAMS reflect the "layers and options" 
characteristics of contemporary networking architectures. The basic com- 
ponents in a STREAMS implementation are referred to as modules. These 
modules, which reside in the kernel, offer a set of processing functions and 
associated service interfaces. From user level, modules can be dynamically 
selected and interconnected to provide any rational processing sequence. Ker- 
nel programming, assembly, and link editing are not required to create the 
interconnection. Modules can also be dynamically "plugged into" existing 
connections from user level. STREAMS' modularity makes the following 
features possible: 

■ User-level programs that are independent of underlying protocols and 
physical communication media 

■ Network architectures and higher-level protocols that are independent 
of underlying protocols, drivers, and physical communication media 

■ Higher-level services that can be created by selecting and connecting 
lower-level services and protocols 

■ Enhanced portability of protocol modules, resulting from STREAMS' 
well-defined structure and interface standards 

In addition to modularity, STREAMS provides developers with integral 
functions, a library of utility routines, and facilities that expedite software 
design and implementation. The principal facilities are as follows: 

■ Buffer management — To maintain STREAMS' own independent buffer 
pool 
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■ Flow control — To conserve STREAMS' memory and processing 
resources 

■ Scheduling — To incorporate STREAMS' own scheduling mechanism 

■ Multiplexing — For processing interleaved data streams, such as occur 
in SNA, X.25, and windows 

■ As3mchronous operation of STREAMS and user processes — Allows 
STREAMS-related operations to be performed efficiently from user level 

■ Error and trace loggers — For debugging and administrative functions 

STREAMS is the standard for AT&T UNIX System data communications 
and networking implementations. The original STREAMS concepts were 
developed in the Information Sciences Research Division of AT&T Bell 
Laboratories (see "A Stream Input-Output System" in the October 1984 
AT&T Bell Laboratories Technical Journal), 



How This Document Is Organized 

The remainder of this manual is organized as follows: 

■ Chapter 2 provides an overview of the applications and benefits of 
STREAMS and the STREAMS mechanism. 

■ Chapter 3 describes how to set up a Stream from user level and how 
this initialization affects the kernel. This and following chapters are 
aimed at developers. 

■ Chapter 4 contains a detailed example and discusses it from user level. 

■ Chapter 5 describes kernel operations associated with the Chapter 4 
example, as well as basic STREAMS kernel facilities. 

■ Chapter 6 includes kernel and user facilities not otherwise described. 

■ Chapter 7 compares certain design features of character I/O device 
drivers with STREAMS modules and drivers. 

■ The Glossary defines terms that are specific to STREAMS. 
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Other Documents 

The STREAMS Programmer's Guide contains more detailed STREAMS infor- 
mation for programmers: how programmers can develop networking applica- 
tions with STREAMS user-level facilities and how system programmers can use 
STREAMS kernel-level facilities to build modules and drivers. 

Section 2 of the Programmer's Reference Manual includes descriptions 
(manual pages) of STREAMS-related system calls and other information. 

Notational Conventions 

The following notational conventions are used throughout this Guide: 

bold User input, such as commands and options to 

commands, and the names of directories and files 
appear in bold. 

italic Names of variables to which values must be 

assigned (such as filename) appear in italic, 

command{numher) A command name followed by a number in 

parentheses refers to the part of a UNIX System 
reference manual that documents that command. 
(There are two reference manuals: the 
User's/System Administrator's Reference Manual 
and the Programmer's Reference ManuaL) For 
example, the notation cat{l) refers to the page in 
section 1 (of the User's /System Administrator's 
Reference Manual) that documents the cat com- 
mand. 
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A Basic View of a Stream 

"STREAMS" is a collection of system calls, kernel resources, and kernel 
utility routines that can create, use, and dismantle a "Stream". A Stream is a 
full-duplex processing and data transfer path between a driver in kernel space 
and a process in user space (see Figure 2-1). 



User 
Process 



Stream 
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Module 



Driver 



External 
Interface 



User Space 
Kernel Space 

downstream 



1' 



(optional) 



pstream 



Figure 2-1: Basic Stream 



A Stream has three parts: a Stream head, module(s) (optional), and a 
driver (also referred to as the Stream end). The Stream head provides the 
interface between the Stream and user processes. Its principal function is to 
process STREAMS-related user system calls. A module processes data that 
travel between the Stream head and driver. A STREAMS driver may be a 
device driver, providing the services of an external I/O device, or an internal 
software driver, commonly called a pseudo-device driver. 
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A Basic View off a Stream 



Using a combination of system calls, kernel routines, and kernel utilities, 
STREAMS passes data between a driver and the Stream head in the form of 
messages. Messages that are passed from the Stream head toward the driver 
are said to travel downstream, and messages passed in the other direction 
travel upstream. 

Data sent to a driver from a user process are packaged into STREAMS mes- 
sages and passed downstream. STREAMS can insert one or more modules 
into a Stream between the Stream head and driver to perform intermediate 
processing of data passing between the Stream head and driver. 



System Calls 

Applications programmers can use the STREAMS facilities by means of a 
set of system calls. This system call interface is upwardly compatible with the 
existing character I/O facilities. The open [see open{2)] system call recognizes 
a STREAMS file and creates a Stream to the specified driver. A user process 
can send and receive data using read [see read{2)] and write [see write{2)] in 
the same manner as character files and devices. The ioctl [see ioctl{2)] system 
call enables application programs to perform functions specific to a particular 
device. In addition, a set of generic STREAMS ioctl commands [see 
$treamio{7)] support a variety of functions for accessing and controlling 
Streams. A close [see close{2)] system call dismantles a Stream. 

The open, close, read, write, and ioctl system calls support the basic set 
of operations on Streams. In addition, new system calls support advanced 
STREAMS facilities. The poll [see poll(2)] system call enables an application 
program to poll multiple Streams for various events. When used with the 
STREAMS LSETSIG ioctl command, poll allows an application to process I/O 
in an as)mchronous manner. The putmsg [see putmsg{2)] and getmsg [see 
getmsg(2)\ system calls enable application programs to interact with STREAMS 
modules and drivers through a service interface (described next). 

These calls are discussed in this document and in the STREAMS 
Programmer's Guide. They are specified in the Programmer's Reference Manual 
and the User's/System Administrator's Reference Manual. 
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STREAMS offers two major benefits for applications programmers: easy 
creation of modules that offer standard data communications services and the 
ability to manipulate those modules on a Stream. 



Creating Service Interfaces 

One benefit of STREAMS is that it simplifies the creation of modules that 
present a service interface to any neighboring application program, module, or 
device driver. A service interface is defined at the boundary of two neighbors. 
In STREAMS, a service interface is a specified set of messages and the rules for 
allowable sequences of these messages across the boundary. A module that 
implements a service interface will receive a message from a neighbor and 
respond with an appropriate action (for example, send back a request to 
retransmit) based on the specific message received and the preceding sequence 
of messages. 

STREAMS provides features that make it easy to design various application 
processes and modules that comply with common service interfaces. If these 
modules are written to comply with industry-standard service interfaces, they 
are called protocol modules. 

In general, any two modules can be connected an3rwhere in a Stream. 
However, rational sequences are generally constructed by connecting modules 
with compatible protocol service interfaces. For example, a module that 
implements an X.25 protocol layer, as shown in Figure 2-2, presents a protocol 
service interface at its input and output sides. In this case, other modules 
should only be connected to the input and output side if they have the com- 
patible X.25 service interface. 

Manipulating lyiodules 

STREAMS provides the capabilities to manipulate modules from user level, 
interchange modules with common service interfaces and to present a service 
interface to a Stream user process. As stated in Chapter 1, the benefits these 
capabilities yield when implementing networking services and protocols 
include 
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■ User-level programs that can be independent of underlying protocols 
and physical communication media 

■ Network architectures and higher-level protocols that can be indepen- 
dent of underlying protocols, drivers^ and physical communication 
media 

■ Higher-level services that can be created by selecting and connecting 
lower-level services and protocols 

The following examples illustrate how STREAMS can benefit developers who 
are creating service interfaces and manipulating modules. 



NOTE 



All protocol modules used below were selected for illustrative purposes. 
Their use does not imply that AT&T offers such modules as products. 



Protocol Portability 

Figure 2-2 shows how the same X.25 protocol module can be used with 
different drivers on different machines by implementing compatible service 
interfaces. The X.25 protocol module interfaces are the Connection-Oriented 
Network Service (CONS) and the Link Access Protocol - Balanced (LAPB) 
driver. 
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Figure 2-2: Protocol Module Portability 



Protocol Substitution 

Alternative protocol modules (and device drivers) can be interchanged on 
the same machine if they are implemented to an equivalent service 
interface(s). 

Protocol Migration 

Figure 2-3 illustrates how STREAMS can migrate functions between kernel 
software and front-end firmware. A common downstream service interface 
allows the transport protocol module to be independent of the number or type 
of modules below. The same transport module will connect without modifica- 
tion to either an X.25 module or X.25 driver that has the same service inter- 
face. 
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By shifting functions between software and firmware, developers can pro- 
duce cost effective, functionally equivalent systems over a wide range of 
configurations. They can rapidly incorporate technological advances. The 
same transport protocol module can be used on a lower-capadty machine, 
where economics may preclude the use of front-end hardware, and also on a 
larger scale system where a front-end is economically justified. 
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Figure 2-3: Protocol Migration 



Module Reusability 

Figure 2-4 shows the same canonical module (for example, one that pro- 
vides delete and kill processing on character strings) reused in two different 
Streams. This module would typically be implemented as a filter, with no 
downstream service interface. In both cases, a TTY interface is presented to 
the Stream's user process, since the module is nearest the Stream head. 
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Figure 2-4: Module Reusability 
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An Advanced View of a Stream 



The STREAMS mechanism constructs a Stream by serially connecting 
kernel-resident STREAMS components, each constructed from a specific set of 
structures. As described earlier, and shown in Figure 2-5, the primary 
STREAMS components are the Stream head, optional module(s), and Stream 
end. 
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Figure 2-5: Stream in More Detail 
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Stream Head 

The Stream head provides the interface between the Stream and an appli- 
cation program. The Stream head processes STREAMS-related system calls 
from the application and performs the bidirectional transfer of data and infor- 
mation between the application (in user space) and messages (in STREAMS' 
kernel space). 

Messages are the only means of transferring data and communicating 
within a Stream. A STREAMS message contains data, status/control informa- 
tion, or a combination of the two. Each message includes a specified message 
type indicator that identifies the contents. 



Modules 

A module performs intermediate transformations on messages passing 
between Stream head and driver. There may be zero or more modules in a 
Stream (zero when the driver performs all the required character and device 
processing). 

Each module is constructed from a pair of QUEUE structures (see Au/Ad 
and Bu/Bd in Figure 2-5). A pair is required to implement the bidirectional 
and symmetrical attributes of a Stream. One QUEUE performs functions on 
messages passing upstream through the module (Au and Bu in Figure 2-5). 
The other QUEUE (Ad and Bd) performs another set of functions on down- 
stream messages. (A QUEUE, which is part of a module, is different from a 
message queue, which is described later.) 

The two QUEUES in a module will generally have distinct functions, that 
is, unrelated processing procedures and data. The QUEUES operate indepen- 
dently so that Au will not know if a message passes through Ad unless Ad is 
programmed to inform Au. Messages and data can be shared only if the 
developer specifically programs the module functions to perform the sharing. 

Each QUEUE can directly access the adjacent QUEUE in the direction of 
message flow (for example, Au to Bu or Stream head to Bd). In addition, 
within a module, a QUEUE can readily locate its mate and access its messages 
(for example, for echoing) and data. 
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Each QUEUE in a module may contain or point to messages, processing 
procedures, or data: 

■ Messages — These are dynamically attached to the QUEUE on a linked 
list ("message queue," see Au and Bd in Figure 2-5) as they pass 
through the module. 

■ Processing procedures — A put procedure, to process messages, must be 
incorporated into each QUEUE. An optional service procedure, to share 
the message processing with the put procedure, can also be incor- 
porated. According to their function, the procedures can send messages 
upstream and/or downstream, and they can also modify the private 
data in their module. 

■ Data — Developers may provide private data (for example, state infor- 
mation and translation tables) if required by the QUEUE to perform 
message processing. 

In general, each of the two QUEUES in a module has a distinct set of all of 
these elements. Additional module elements will be described later. 
Although depicted as distinct from modules (see Figure 2-5), the Stream head 
and Stream end also contain a pair of QUEUES. 



Stream End 

A Stream end is a module in which the module's processing procedures 
are the driver routines. The procedures in the Stream end are different from 
those in other modules, because they are accessible from an external device 
and because the STREAMS mechanism allows multiple Streams to be con- 
nected to the same driver. 

The driver can be a device driver, providing an interface between kernel 
space and an external communications device, or an internal pseudo-device 
driver. A pseudo-device driver is not directly related to any external device, 
and it performs functions internal to the kernel. The multiplexing driver dis- 
cussed in Chapter 6 is a pseudo-device driver. 

Device drivers must transform all data and status/control information 
between STREAMS message formats and their external representation. Differ- 
ences between STREAMS and character device drivers are discussed in Chapter 
7. 
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Building a Stream 



A Stream is created on the first open system call to a character special file 
corresponding to a STREAMS driver. A STREAMS device is distinguished from 
other character devices by a field contained in the associated cdevsw device 
table entry. 

A Stream is usually built in two steps. Step one creates a minimal Stream 
consisting of just the Stream head and device driver. Step one has three parts: 

1. The head and driver structures are allocated and initialized 

2. The modules in the head and end are linked to each other to form a 
Stream 

3. The driver open routine is called 

Step two adds modules to produce an expanded Stream (see Figure 3-1). 



Minimal 
STREAM 



STREAM 
HEAD 



Expanded 
STREAM 



STRIAM 
HEAD 



I 



CANONPROC 
module 



I QUEUE pair \ 

raw TTY 
device driver 



I QUEUE pair \ 

raw TTY 
device driver 



Figure 3-1: Setting Up a Stream 
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If the driver performs all of the required character and device processing, 
no modules need be added to a Stream. Examples of STREAMS drivers 
include a raw tty driver (one that passes along input characters without 
change) and a driver with multiple Strean\s open to it (one that corresponds to 
multiple minor devices opened to a character device driver). 

When the driver receives characters from the device, it places them into 
messages. The messages are then transferred to the next Stream component, 
the Stream head, which extracts the contents of the message and copies them 
to user space. Similar processing occurs for downstream character output; the 
Stream head copies data from user space into messages and sends them to the 
driver. 



Expanded Streams 

As the second step in building a Stream, modules can be added to the 
Stream. In the right-hand Stream in Figure 3-1, the CANONPROC module 
was added to provide additional processing on the characters sent between 
head and driver. 

Modules are added and removed from a Stream in last-in-first-out (LIFO) 
order. They are inserted and deleted at the Stream head by means of the 
ioctl system call. In the Stream on the left of Figure 2-4, the X.25 module 
was the first added to the Stream, followed by the Class 1 Transport and 
Canonical modules. To replace the Class 1 module with a Class module, 
the Canonical module would have to be removed first, then the Class 1 
module, then a Class module would be added, and the Canonical module 
put back. 

Because adding and removing modules resembles stack operations, the 
add is called a push, and the remove, a pop. Push and pop are two of the 
ioctl functions included in the STREAMS subset of ioctl system calls. These 
commands perform various manipulations and operations on Streams. The 
modules manipulated in this manner are called pushable modules, in contrast 
to the modules contained in the Stream head and end. This stack terminology 
applies only to the setup, modification, and breakdown of a Stream. 



NOTE 



Subsequent use of the word "module" will refer to those pushable modules 
between Stream head and end. 
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The Stream head processes the ioctl and executes the push, which is 
analogous to opening the Stream driver. Modules are referenced by a unique 
symbolic name, contained in the STREAMS fmodsw module table (similar to 
the cdevsw table associated with a device file). The module table and module 
name are internal to STREAMS and are accessible from user space only 
through STREAMS ioctl system calls. The fmodsw table points to the module 
template in the kernel. When a module is pushed, the template is located, the 
module structures for both QUEUES are allocated, and the template values are 
copied into the structures. 

In addition to the module elements described in "A Basic View of a 
Stream " section of Chapter 2, each module contains pointers to an open rou- 
tine and a close routine. The open is called when the module is pushed, and 
the close is called when the module is popped. Module open and close pro- 
cedures are similar to a driver open and close. 

As in other files, a STREAMS file is closed when the last process open to it 
closes the file by a close system call. This system call causes the Stream to be 
dismantled (modules popped and the driver close executed). 



Pushable Modules 

Modules are pushed onto a Stream to provide special functions and/or 
additional protocol layers. In Figure 3-1, the Stream on the left is opened in a 
minimal configuration with a raw tty driver and no other module added. The 
driver receives one character at a time from the device, places the character in 
a message, and sends the message upstream. The Stream head receives the 
message, extracts the single character, and copies it into the reading process 
buffer to send to the user process in response to a read system call. When the 
user process wants to send characters back to the driver, it issues a write sys- 
tem call, and the characters are sent to the Stream head. The head copies the 
characters into one or more multicharacter messages and sends them down- 
stream. An application program requiring no further kernel character process- 
ing would use this minimal Stream. 

A user requiring a more terminal-like interface would need to insert a 
module to perform functions such as echoing, character-erase, and line-kill. 
Assuming that the CANONPROC module in Figure 3-1 fulfills this need, the 
application program first opens a raw tty Stream. Then, the CANONPROC 
module is pushed above the driver to create a Stream of the form shown on 
the right of the figure. The driver is not aware that a module has been placed 
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above it and therefore continues to send single-character messages upstream. 
The module receives single-character messages from the driver, processes the 
characters, and accumulates them into line strings. Each line is placed into a 
message and sent to the Stream head. The head now finds more than one 
character in the messages it receives from downstream. 

Stream head implementation accommodates this change in format 
automatically and transfers the multicharacter data into user space. The 
Stream head also keeps track of messages partially transferred into user space, 
as occurs when the current user read buffer can only hold part of the current 
message. Downstream operation is not affected: the head sends, and the 
driver receives, multiple character messages. 

Note that the Stream head provides the interface between the Stream and 
user process. Modules and drivers do not have to implement user interface 
functions other than open and close. 
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STREAMS System Calls 



After a Stream has been opened, STREAMS-related system calls allow a 
user process to insert and delete (push and pop) modules. That process can 
then control the operation of the Stream head, modules, and drivers, and can 
send and receive messages containing data and control information. This 
chapter presents an example of some of the basic functions available to 
STREAMS-based applications via the system calls. Additional functions are 
described at the end of this chapter and in Chapter 6. 

The full set of STREAMS-related system calls follows: 



open 


Open a Stream (described in Chapter 3) 


close 


Close a Stream (described in Chapter 3) 


read 


Read data from a Stream 


write 


Write data to a Stream 


ioctl 


Control a Stream 


getmsg 


Receive the message at Stream head 


putmsg 


Send a message downstream 


poll 


Notify the application program when selected events occur 




on a Stream 



The following two-part example describes a Stream that controls the data 
communication characteristics of a connection between an asynchronous ter- 
minal and a tty port. It illustrates basic user level STREAMS features, then 
shows how messages can be used. Chapter 5 discusses the kernel level 
Stream operations corresponding to the user-level operations described in this 
chapter. See the STREAMS Programmer's Guide for more detailed examples of 
STREAMS applications, modules, and drivers. 
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An Asynchronous Protocol Stream 
Example 

In the example, our computer runs the UNIX System and supports dif- 
ferent kinds of asynchronous terminals, each logging in on its own port. The 
port hardware is limited in function; for example, it detects and reports line 
and modem status, but does not check parity. 

Communications software support for these terminals is provided by 
means of a STREAMS-implemented asynchronous protocol. The protocol 
includes a variety of options that are set when a terminal operator dials in to 
log on. The options are determined by a getty-type STREAMS user process, 
getstrm, which analyzes data sent to it through a series of dialogs (prompts 
and responses) between the process and terminal operator. 

The process sets the terminal options for the duration of the connection by 
pushing modules onto the Stream or by sending control messages to cause 
changes in modules, or in the device driver, already on the Stream. The 
options supported include the following: 

■ ASCII or EBCDIC character codes 

■ Parity (odd, even, or none) for ASCII code 

■ Echo or not echo input characters 

■ Canonical input and output processing or transparent (raw) character 
handling 

These options are set with the following modules: 

CHARPROC Provides input character processing functions, including 
dynamically settable (via control messages passed to the 
module) character echo and parity checking. The 
module's default settings are to echo characters and not 
check character parity. 

CANONPROC Performs canonical processing on ASCII characters 

upstream and downstream. Note that this performs some 
processing in a different manner from the standard UNIX 
System character I/O tty subsystem. 
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ASCEBC Translates EBCDIC code to ASCII upstream and ASCII to 

EBCDIC downstream. 



Initializing the Stream 

At system initialization a user process, getstrm, is created for each tty port. 
getstm opens a Stream to its port and pushes the CHARPROC module onto 
the Stream, by use of an ioctl L-PUSH command. Then, the process issues a 
getmsg system call to the Stream and sleeps until a message reaches the 
Stream head. The Stream is now in its idle state. 

The initial idle Stream, shown in Figure 4-1, contains only one pushable 
module, CHARPROC. The device driver is a limited-function, raw tty driver 
connected to a limited-function communication port. The driver and port 
transparently transmit and receive one unbuffered character at a time. 



getstrm 
STREAM 

heKd 

m 

CHARPROC 
module 

QUEUE Pair 

raw TTY 
device driver 



Figure 4-1: Idle Stream Configuration for Example 
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Upon receipt of initial input from a tty port, getstrm establishes a connec- 
tion with the terminal, analyzes the option requests, verifies them, and issues 
STREAMS system calls to set the options. After setting up the options, getstrm 
creates a user application process. Later, when the user terminates that appli- 
cation, getstrm restores the Stream to its idle state by use of system calls. 

The next step is to analyze in more detail how the Stream sets up the 
communications options. Before doing so, let's examine how messages are 
handled in STREAMS. 



Message Types 

All STREAMS messages are assigned message types to indicate their 
intended use by modules and drivers and to determine their handling by the 
Stream head. A driver or module can assign most types to a message it gen- 
erates, and a module can modify a message's type during processing. The 
Stream head will convert certain system calls to specified message types and 
send them downstream, and it will respond to other calls by copying the con- 
tents of certain message types that were sent upstream. Messages exist only 
in the kernel, so a user process can only send and receive buffers. The pro- 
cess is not explicitly aware of the message type, but it may be aware of mes- 
sage boundaries, depending on the system call used (see the distinction 
between getmsg and read in the next section). 

Most message types are internal to STREAMS and can only be passed from 
one STREAMS module to another. A few message types, including M_DATA, 
M_PROTO, and M_PCPROTO, can also be passed between a Stream and a user 
process. M_DATA messages carry data within a Stream and between a Stream 
and a user process. M_PROTO or M_PCPROTO messages carry both data and 
control information. However, the distinction between control information and 
data is generally determined by the developer when implementing a particular 
Stream. Control information includes service interface information, carried 
between two Stream entities that present service interfaces, and condition or 
status information, which may be sent between any two Stream entities 
regardless of their interface. An M_PCPROTO message has the same general 
use as an M— PROTO, but the former moves faster through a Stream (see 
"Message Queue Priority" in Chapter 6). 
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Sending and Receiving IMessages 

putmsg is a STREAMS-related system call that sends messages; it is similar 
to write, putmsg provides a data buffer which is converted into an M_DATA 
message, and can also provide a separate control buffer to be placed into an 
NLPROTO or M-PCPROTO block, write provides byte-stream data to be con- 
verted into M_DATA messages. 

getmsg is a STREAMS-related system call that accepts messages; it is simi- 
lar to read. One difference between the two calls is that read accepts only 
data (messages sent upstream to the Stream head as message type M_DATA), 
such as the characters entered from the terminal, getmsg can simultaneously 
accept both data and control information (messages sent upstream as types 
M-PROTO or M_PCPROTO). getmsg also differs from read in that it preserves 
message boundaries so that the same boundaries exist above and below the 
Stream head (that is, between a user process and a Stream), read generally 
ignores message boundaries, processing data as a byte stream. 

Certain STREAMS ioctl commands, such as I_STR, also cause messages to 
be sent or received on the Stream. L_STR provides the general "ioctl" capa- 
bility of the character I/O subsystem. A user process above the Stream head 
can issue putmsg, getmsg, the I_STR ioctl command, and certain other 
STREAMS-related system calls. Other STREAMS ioctls perform functions that 
include changing the state of the Stream head, pushing and popping modules, 
or returning special information, ioctl commands are described in more detail 
in the STREAMS Programmer's Guide, 

In addition to message types that explicitly transfer data to a process, 
some messages sent upstream result in information transfer. When these mes- 
sages reach the Stream head, they are transformed into various forms and sent 
to the user process. These forms include signals, error codes, and call return 
values. 



Using Messages in tlie Example 

Returning to the asynchronous protocol example, the Stream was in its 
idle configuration (see Figure 4-1). getstrm had issued a getmsg and was 
sleeping until the arrival of a message from the Stream head. Such a message 
would result from a driver detecting activity on the associated tty port. 
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An incoming call arrives at port one and causes a ring-detect signal in the 
modem. The driver receives the ring signal, answers the call, and sends 
upstream an M_PROTO message containing information indicating an incom- 
ing call, getstrm is notified of all incoming calls, although it can choose to 
refuse the call because of system limits. In this idle state, getstrm will also 
accept M_PROTO messages indicating, for example, error conditions such as 
detection of line or modem problems on the idle line. 

The M_PROTO message contaiiung notification of the incoming call flows 
upstream from the driver into CHARPROC. CHARPROC inspects the message 
type, determines that message processing is not required, and passes the 
unmodified message upstream to the Stream head. The Stream head copies 
the message into the getmsg buffers (one buffer for control information, the 
other for data) associated with getstrm and wakes up the process, getstrm 
sends its acceptance of the incoming call with a putmsg system call, which 
results in a downstream M— PROTO message to the driver. 

Then, getstrm sends a prompt to the operator with a write and issues a 
getmsg to receive the response. A read could have been used to receive the 
response, but the getmsg call allows concurrent monitoring for control 
(M-PROTO and M-PCPROTO) information, getstrm will now sleep until the 
response characters, or information regarding possible error conditions 
detected by modules or driver, are sent upstream. 

The first response, sent upstream in a M_DATA block, indicates that the 
code set is ASCII and that canonical processing is requested, getstrm imple- 
ments these options by pushing CANONPROC onto the Stream, above CHAR- 
PROC, to perform canonical processing on the input ASCII characters. 

The response to the next prompt requests even parity checking, getstrm 
sends an ioctl I_STR command to CHARPROC, requesting the module to per- 
form even parity checking on upstream characters. When the dialog indicates 
protocol option setting is complete, getstrm creates an application process. At 
the end of the connection, getstrm will pop CANONPROC, and then send a 
L-STR to CHARPROC requesting the module to restore the no-parity idle state 
(CHARPROC remains on the Stream). 
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As a result of the above dialogs, the terminal at port one operates in the 
following configuration: 

■ ASCII, even parity 

■ Echo 

■ Canonical processing 

In sinular fashion, an operator at a different type of tenninal on port two 
requests a different set of options, resulting in the following configuration: 

■ EBCDIC 

■ No Echo 

■ Canonical processing 

The resulting Streams for the two ports are shown in Figure 4-2. For port 
one, on the left, the modules in the Stream are CANONPROC and CHARPROC. 

For port two, on the right, the resulting modules are CANONPROC, 
ASCEBC and CHARPROC. ASCEBC has been pushed on this Stream to 
translate between the ASCII interface at the downstream side of CANONPROC 
and the EBCDIC interface of the upstream output side of CHARPROC. In addi- 
tion, getstrm has sent an I_STR to the CHARPROC module in this Stream 
requesting it to disable echo. The resulting modification to CHARPROC's func- 
tions is indicated by the word "modified" in the right Stream of Figure 4-2. 
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Figure 4-2: As)mchronous Terminal Streams 



4-8 STREAMS PRIMER 



An Asynchronous Protocol Stream Example 



Since CHARPROC is now performing no function for port two, it might 
have been popped from the Stream to be reinserted by getstrm at the end of 
connection. However, the low overhead of STREAMS does not require its 
removal. The module remains on the Stream, passing messages unmodified 
between ASCEBC and the driver. At the end of the connection, getstrm 
restores this Stream to its idle configuration of Figure 4-1 by popping the 
added modules and then sending an I_STR to CHARPROC to restore the echo 
default. 

Note that the tty driver shown in Figure 4-2 handles minor devices. Each 
minor device has a distinct Stream connected from user space to the driver. 
This ability to handle multiple devices is a standard STREAMS feature, similar 
to the minor device mechanism in character I/O device drivers. 
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The previous example illustrates basic STREAMS concepts. Alternate, more 
efficient STREAMS calls or mechanisms could have been used in place of those 
described earlier. Some of the alternatives are described in Chapter 6, and 
others are addressed in the STREAMS Programmer's Guide. 

For example, the initialization process that created a getstrm for each tty 
port could have been implemented as a "supergetty" by use of the 
STREAMS-related poll system call. As described in Chapter 6, poll allows a 
single process to efficiently monitor and control multiple Streams. The 
"supergetty" process would handle all of the Stream and terminal protocol 
initialization and would create application processes only for established con- 
nections. 

The M— PROTO notification sent to getstrm could have been sent by the 
driver as an M-_SIG message that causes a specified signal to be sent to the 
process. As discussed previously under "Message Types," error and status 
information can also be sent upstream from a driver or module to user 
processes by means of different message types. These messages will be 
transformed by the Stream head into a signal or error code. 

Finally, an ioctl L_STR command could have been used in place of a 
putmsg M-JPROTO message to send information to a driver. The sending pro- 
cess must receive an explicit response from an L-STR by a specified time 
period or an error will be returned. A response message must be sent 
upstream by the destination module or driver to be translated into the user 
response by the Stream head. 
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Introduction 



This chapter introduces the use of the STREAMS mechanism in the kernel 
and describes some of the tools provided by STREAMS to assist in the develop- 
ment of modules and drivers. In addition to the basic message-passing 
mechanism and QUEUE Stream linkage described previously, the STREAMS 
mechanism consists of various facilities, namely, buffer management, the 
STREAMS scheduler, processing and message priority, flow control, and multi- 
plexing. Over 30 STREAMS utility routines and macros are available to mani- 
pulate and use these facilities. 

The key elements of a STREAMS kernel implementation are the processing 
routines in the module and drivers, and preparation of required data struc- 
tures. The structures are described in the STREAMS Programmer's Guide. The 
following sections provide further information on messages and on the pro- 
cessing routines that operate on them. The example described in Chapter 4 is 
continued, associating the user-level operations described there with kernel 
operations. 
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As shown in Figure 5-1, a STREAMS message consists of one or more 
linked message blocks. That is, the first message block of a message may be 
attached to other message blocks that are part of the same message. Multiple 
blocks in a message can occur, for example, as the result of processing that 
adds header or trailer data to the data contained in the message, or because of 
message-buffer size limitations, which cause the data to span multiple blocks. 
When a message is composed of multiple message blocks, the message type of 
the first block determines the type of the entire message, regardless of the 
types of the attached message blocks. 



Message 
Block 
(type) 

T 

Message 
Block 

Message 
Block 

Figure 5-1: A Message 



STREAMS allocates a message as a single block containing a buffer of a 
certain size (see the next section). If the data for a message exceed the size of 
the buffer containing the data, the procedure can allocate a new block contain- 
ing a larger buffer, copy the current data to it, insert the new data, and de- 
allocate the old block. Alternately, the procedure can allocate an additional 
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(smaller) block, place the new data in the new message block, and link it 
before or after the initial message block. Both alternatives yield one new mes- 
sage. 

Messages can exist standalone, as shown in Figure 5-1, when the message 
is being processed by a procedure, or a message can await processing on a 
linked list of messages, called a message queue, in a QUEUE. In Figure 5-2, 
Message 1 is linked to Message 2. 



queue 
header 



Message 
1 



next 



message 




Message 
2 

next 
message 



Figure 5-2: Messages on a Message Queue 



When a message is on a queue, the first block of the message contains links to 
preceding and succeeding messages on the same message queue, and it can 
contain a link to the second block of the message (if present). The message 
queue head and tail are contained in the QUEUE. 
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STREAMS utility routines enable developers to manipulate messages and 
message queues. 

Message Allocation 

STREAMS maintains its own storage pool for messages. A procedure can 
request the allocation of a message of a specified size at one of three 
message-pool priorities. The allocb utility will return a message containing a 
single block with a buffer of at least the size requested, provided there is a 
buffer available at the priority requested. When requesting priority for mes- 
sages, developers must weigh their process's need for resources against the 
needs of other processes on the same machine. 

Message pool priority generally has no effect on allocation until the pool 
falls below internal STREAMS thresholds. When this occurs, allocb may refuse 
a lower priority request for a message of size "x" while granting a higher 
priority request for the same size message. As examples of priority usage, 
storage for an urgent control message, such as an M— HANGUP or 
M_PCPROTO, could be requested at high priority. An M_DATA buffer for 
holding input might be requested at medium priority, and an output buffer 
(presuming the output data can wait in user space) at lowest priority. 
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The procedures in the QUEUE are the software routines that process mes- 
sages as they transit the QUEUE. The processing is generally performed 
according to the message type and can result in a modified message, new 
message(s), or no message. A resultant message is generally sent in the same 
direction in which it was received by the QUEUE, but may be sent in either 
direction. A QUEUE will always contain a put procedure and may also contain 
an associated service procedure. 



Put Procedures 

A put procedure is the QUEUE routine that receives messages from the 
preceding QUEUE in the Stream. Messages are passed between QUEUES by 
having a procedure in one QUEUE call the put procedure contained in the fol- 
lowing QUEUE. A call to the put procedure in the appropriate direction is 
generally the only way to pass messages between modules (unless otherwise 
indicated, "modules" infers "module, driver, and Stream head"). QUEUES in 
pushable (see Chapter 3) modules contain a put procedure. In general, there 
is a separate put procedure for the read and write QUEUES in a module, 
because most Streams have "full duplex" operation. 

A put procedure is associated with immediate (as opposed to deferred, see 
below) processing on a message. Each module accesses the adjacent put pro- 
cedure as a subroutine. For example, consider that modA, modB, and modC are 
three consecutive modules in a Stream, with modC connected to the Stream 
head. If modA receives a message to be sent upstream, modA processes that 
message and calls modB's put procedure, which processes it and calls modCs 
put procedure, which processes it and calls the Stream head's put procedure. 
Thus, the message will be passed along the Stream in one continuous process- 
ing sequence. This sequence has the benefit of completing the entire process- 
ing in a short time with low overhead (subroutine calls). 

In addition, there are situations where the put procedure cannot immedi- 
ately process the message but must hold it until processing is allowed. The 
most typical examples of this are a driver that must wait until the current out- 
put completes before sending the next message, and the Stream head, when it 
must wait until a process initiates a read on the Stream. 
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Service Procedures 

STREAMS allows a service procedure to be contained in each QUEUE, in 
addition to the put procedure. A service procedure is not required in a QUEUE 
and is associated with deferred processing. If a QUEUE has both a put and 
service procedure, message processing wUl generally be divided between the 
procedures. The put procedure is always called first, from a preceding QUEUE. 
After the put procedure completes its part of the message processing, it 
arranges for the service procedure to be called, by passing the message to the 
putq routine, putq does two things: it places the message on the message 
queue of the QUEUE (see Figure 5-2) and links the QUEUE to the end of the 
STREAMS scheduling queue. When putq returns to the put procedure, the 
procedure typically exits. Some time later, the service procedure will be called 
by the STREAMS scheduler. 

The STREAMS scheduler is separate and distinct from the UNIX System 
process scheduler. It is concerned only with QUEUES linked on the STREAMS 
scheduling queue. The scheduler calls the service procedure of the scheduled 
QUEUE in a FIFO manner, one at a time. 

Having both a put and service procedure in a QUEUE enables STREAMS to 
provide the rapid response and the queuing required in multiuser systems. 
The put procedure allows rapid response to certain data and events, such as 
software echoing of input characters. Put procedures effectively have higher 
priority than any scheduled service procedures. When called from the preced- 
ing STREAMS component, a put procedure executes before the scheduled ser- 
vice procedures of any QUEUE are executed. 

The service procedure implies message queuing. Queuing results in 
deferred processing of the service procedure, following all other QUEUES 
currently on the scheduling queue. For example, terminal output and input 
erase and kill processing would typically be performed in a service procedure, 
because this type of processing does not have to be as timely as echoing. Use 
of a service procedure also allows processing time to be more evenly spread 
among multiple Streams. As in the use of the put procedure, there will gen- 
erally be a separate service procedure for each QUEUE in a module. The flow 
control mechanism (see Chapter 6) uses the service procedures. 
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The following continues the example of Chapter 4, which describes 
STREAMS kernel operations and associates them, where relevant, with Chapter 
4 user-level system calls in the example. As a result of initializing operations 
and pushing a module, the Stream for port one has the following configura- 
tion: 
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Figure 5-3: Operational Stream for Example 



As shown in Figure 5-3, the upstream QUEUE is also referred to as the 
read QUEUE, reflecting the message flow in response to a read system call. 
Correspondingly, downstream is referred to as the write QUEUE. Read side 
processing is discussed first. 
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Read Side Processing 

In our example, read side processing consists of driver processing, CHAR- 
PROC processing, and CANONPROC processing. 

Driver Processing 

In the example, the user process is blocked on the getmsg system call 
while waiting for a message to reach the Stream head, and the device driver 
independently waits for input of a character from the port hardware, or for a 
message from upstream. Upon receipt of an input character interrupt from the 
port, the driver places the associated character in a previously allocated 
NL-DATA message. Then, the driver sends the message to the CHARPROC 
module by calling CHARPROC's upstream put procedure. On return from 
CHARPROC, the driver calls the allocb utility routine to get another message 
for the next character. 

CHARPROC 

CHARPROC has both put and service procedures on its read side. In the 
example, the other QUEUES in the modules also have put and service pro- 
cedures. 
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Figure 5-4: Module Put and Service Procedures 



When the driver calls CHARPROC's read QUEUE put procedure, the pro- 
cedure checks private data flags in the QUEUE. In this case, the flags indicate 
that echoing is to be performed. Recall that echoing is optional and that we 
are working with port hardware which cannot automatically echo. CHAR- 
PROC causes the echo to be transmitted back to the terminal, by first making a 
copy of the message with a STREAMS utility. Then, CHARPROC uses another 
utility to obtain the address of its own vmte QUEUE. Finally, the CHARPROC 
read put procedure calls its write put procedure and passes it the message 
copy. The write procedure sends the message to the driver to effect the echo 
and then returns to the read procedure. 

This part of read side processing is implemented with put procedures, so 
the entire processing sequence occurs as an extension of the driver input char- 
acter interrupt. The CHARPROC read and write put procedures appear to the 
driver as subroutines (nested in the case of the write procedure). This manner 
of processing is intended to produce the character echo in a minimal time 
frame. 
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After returning from echo processing, the CHARPROC read put procedure 
checks another of its private data flags and determines that parity checking 
should be performed on the input character. Parity should most reasonably 
be checked as part of echo processing. However, for this example, parity is 
checked only when the characters are sent upstream. This relaxes the timing 
in which the checking must occur; that is, it can be deferred along with the 
canonical processing. CHARPROC uses putq to schedule the (original) mes- 
sage for parity check processing by its read service procedure. When the 
CHARPROC read service procedure is complete, it forwards the message to the 
read put procedure of CANONPROC. Note that if parity checking were not 
required, the CHARPROC put procedure would call the CANONPROC put pro- 
cedure directly. 

CANONPROC 

CANONPROC performs canonical processing. As implemented, all read 
QUEUE processing is performed in its service procedure so that CANONPROC's 
put procedure simply calls putq to schedule the message for its read service 
procedure and then exits. The service procedure extracts the character from 
the message buffer and places it in the "line buffer," which is contained in 
another M-DATA message the service procedure is constructing. Then, the 
message which contained the single character is returned to the buffer pool. If 
the character received was not an end-of-line, CANONPROC exits. Otherwise, 
a complete line has been assembled, and CANONPROC sends the message 
upstream to the Stream head, which unblocks the user process from the 
getmsg call and passes it the contents of the message. 



Write Side Processing 

The write side of this Stream carries two kinds of messages from the user 
process: ioctl messages for CHARPROC and M-DATA messages to be output 
to the terminal. 

ioctl messages are sent downstream as a result of an I_STR ioctl system 
call. When CHARPROC receives an ioctl message type, it processes the mes- 
sage contents to modify internal QUEUE flags and then uses a utility to send 
an acknowledgment message upstream (read side) to the Stream head. The 
Stream head acts on the acknowledgment message by unblocking the user 
from the ioctl. 
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For terminal output, it is presumed that M_DATA messages, sent by write 
system calls, contain multiple characters. In general, STREAMS returns to the 
user process immediately after processing the write call so that the process 
can send additional messages. Flow control, described in the next chapter, 
will eventually block the sending process. The messages can queue on the 
write side of the driver because of character transnussion timing. When a 
message is received by the driver's write put procedure, the procedure will use 
putq to place the message on its write side service message queue if the driver 
is currently transmitting a previous message buffer. However, there is gen- 
erally no write QUEUE service procedure in a device driver. Driver output 
interrupt processing takes the place of scheduling and performs the service 
procedure functions, removing messages from the queue. 



Analysis 

For reasons of efficiency, a module implementation would generally avoid 
placing one character per message and using separate routines to echo and 
parity check each character, as was done in this example. Nevertheless, even 
this design )delds potential benefits. Consider a case where alternate, more 
intelligent port hardware was substituted. If the hardware processed multiple 
input characters and performed the echo and parity-checking functions of 
CHARPROC, then the new driver could be implemented to present the same 
interface as CHARPROC. Other modules such as CANONPROC could continue 
to be used without modification. 
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Introduction 



The previous chapters described the basic concepts of constructing a 
Stream and utilizing the STREAMS mechanism. Additional STREAMS features 
are provided to handle characteristic problems of protocol implementation, 
such as flow control, and to assist in development. 

There are also kernel and user-level facilities that support the implementa- 
tion of advanced functions, such as multiplexers, and allow asynchronous 
operation of a user process and STREAMS input and output. 
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Message Queue Priority 



As mentioned in the previous chapter, the STREAMS scheduler operates 
strictly FIFO so that each QUEUE'S service procedure receives control in the 
order it was scheduled. When a service procedure receives control, it may 
encounter multiple messages on its message queue. This buildup can occur if 
there is a long interval between the time a message is queued by a put pro- 
cedure and the time that the STREAMS scheduler calls the associated service 
procedure. In this interval, there can be multiple calls to the put procedure 
causing multiple messages. The service procedure always processes all mes- 
sages on its message queue unless prevented by flow control (see next sec- 
tion). Each message must pass through all the modules connecting its origin 
and destination in the Stream. 

If service procedures were used in all QUEUES and there was no message 
priority, then the most recently scheduled message would be processed after 
all the other scheduled messages on all Streams had been processed. In cer- 
tain cases, message t)^es containing urgent information (such as a break or 
alarm conditions) must pass through the Stream quickly. To accommodate 
these cases, STREAMS provides two classes of message queuing priority, ordi- 
nary and high. STREAMS prevents high-priority messages from being blocked 
by flow control and causes a service procedure to process them ahead of all 
ordinary priority messages on the procedure's queue. This results in the 
high-priority message transiting each module with minimal delay. 
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Figure 6-1: Streams Message Priority 
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Message Queue Priority 



The priority mechanism operates as shown in Figure 6-1. Message queues 
are generally not present in a QUEUE unless that QUEUE contains a service 
procedure. When a message is passed to putq to schedule the message for 
service procedure processing, putq places the message on the message queue 
in priority order. High priority messages are placed ahead of all ordinary 
priority messages but behind any other high priority messages on the queue. 
STREAMS utilities deliver the messages to the processing service procedure 
FIFO within each priority class. The service procedure is unaware of the mes- 
sage priority and simply receives the next message. 

Message priority is defined by the message type; once a message is 
created, its priority cannot be changed. Certain message tjrpes come in 
equivalent high/ordinary priority pairs (for example, M_PCPROTO and 
M_-PROTO) so that a module or device driver can choose between the two 
priorities when sending information. 
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Flow Control 



Even on a well-designed system, general system delays, malfunctions, and 
excessive message accumulation on one or more Streams can cause the mes- 
sage buffer pools to become depleted. Additionally, processing bursts can 
arise when a service procedure in one module has a long message queue and 
processes all its messages in one pass. STREAMS provides two independent 
mechanisms to guard its message buffer pools from being depleted and to 
minimize long processing bursts at any one module. 



NOTE 



Flow control is only applied to normal priority messages (see previous sec- 
tion) and not to high priority messages. 



The first flow control mechanism is global and automatic and is related to 
the message pool priority, discussed in the "Message Storage Pool" section of 
Chapter 5. When the Stream head requests a message buffer in response to a 
putmsg or write system call, it uses the lowest level of priority. Since buffer 
availability is based on priority and buffer pool levels, the Stream head will be 
among the first modules refused a buffer when the pool becomes depleted. In 
response, the Stream head will block user output until the STREAMS buffer 
pool recovers. As a result, output has a lower priority than input. 

The second flow control mechanism is local to each Stream, advisory 
(voluntary), and limits the number of characters that can be queued for pro- 
cessing at any QUEUE in a Stream. This mechanism limits the buffers and 
related processing at any one QUEUE and in any one Stream, but does not 
consider buffer pool levels or buffer usage in other Streams. 

The advisory mechanism operates between the two nearest QUEUES in a 
Stream containing service procedures (see diagram on next page). Messages 
are generally held on a message queue only if a service procedure is present in 
the associated QUEUE. 

Messages accumulate at a QUEUE when its service procedure processing 
does not keep pace with the message arrival rate, or when the procedure is 
blocked from placing its messages on the following Stream component by the 
flow control mechanism. Pushable modules contain independent upstream 
and downstream limits, which are set when a developer specifies high-water 
and low-water control values for the QUEUE. The Stream head contains a 
preset upstream limit, which can be modified by a special message sent from 
downstream, and a driver may contain a downstream limit. 
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Flow control operates as follows: 

1. Each time a STREAMS message-handling routine (for example, putq) 
adds or removes a message from a message queue in a QUEUE, the 
limits are checked. STREAMS calculates the total size of all message 
blocks on the message queue. 

2. The total is compared to the QUEUE high-water and low- water values. 
If the total exceeds the high-water value, an internal full indicator is 
set for the QUEUE. The operation of the service procedure in this 
QUEUE is not affected if the indicator is set, and the service procedure 
continues to be scheduled. 

3. The next part of flow-control processing occurs in the nearest preced- 
ing QUEUE that contains a service procedure. In the diagram below, if 
D is full and C has no service procedure, then B is the nearest preced- 
ing QUEUE. 
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Figure 6-2: Flow Control 



4. The service procedure in B uses a STREAMS utility routine to see if a 
QUEUE ahead is marked full. If messages cannot be sent, the 
scheduler blocks the service procedure in B from further execution. B 
remains blocked until the low- water mark of the full QUEUE, D, is 
reached. 

5. While B is blocked, any non-priority messages that arrive at B will 
accumulate on its message queue (recall that priority messages are not 
blocked). In turn, B can reach a full state and the full condition will 
propagate back to the last module in the Stream. 
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6. When the service procedure processing on D causes the message block 
total to fall below the low-water mark, the full indicator is turned off. 
Then, STREAMS automatically schedules the nearest preceding blocked 
QUEUE (B in this case), getting things moving again. This automatic 
scheduling is known as back-enabling a QUEUE. 

Note that to use flow control, a developer need only call the utility that 
tests if a full condition exists ahead, plus perform some housekeeping if it 
does. Everything else is automatically handled by STREAMS. Additional flow 
control features are described in the STREAMS Programmer's Guide. 
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STREAMS multiplexing supports the development of internetworking pro- 
tocols such as IP and ISO CLNS, the processing of interleaved data streams 
such as in SNA, X.25, and terminal window facilities. 

STREAMS multiplexers (also called pseudo-device drivers) are created in 
the kernel by interconnecting multiple Streams, Conceptually, there are two 
kinds of multiplexers that developers can build with STREAMS, namely, upper 
and lower multiplexers. Lower multiplexers have multiple lower Streams 
between device drivers and the multiplexer, and upper multiplexers have mul- 
tiple upper Streams between user processes and the multiplexer. 
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Figure 6-3: Internet Multiplexing Stream 



Figure 6-3 shows an example of a lower multiplexer. This configuration 
would typically occur where internetworking functions were included in the 
system. This Stream contains two types of drivers: the Ethernet, LAPB, and 
IEEE 802.2, which are hardware device drivers that terminate links to other 
nodes, and the IP (Internet Protocol), which is a multiplexer. 

The IP multiplexer switches messages among the various nodes (lower 
Streams) or sends them upstream to user processes in the system. In this 
example, the multiplexer expects to see an 802.2 interface downstream; for the 
Ethernet and LAPB drivers, the Net 1 and Net 2 modules pro^dde service 
interfaces to the two non-802.2 drivers and the IF multiplexer. 
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Figure 6-3 depicts the IP multiplexer as part of a larger Stream. The 
Stream, as shown in the dotted rectangle, would generally have an upper TCP 
multiplexer and additional modules. Multiplexers could also be cascaded 
below the IP driver if the device drivers were replaced by multiplexer drivers. 
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Figure 6-4: X.25 Multiplexing Stream 



Figure 6-4 shows an upper multiplexer. In this configuration, the driver 
routes messages between the lower Stream and one of the upper Streams. 
This Stream performs X.25 multiplexing to multiple independent SVC 
(Switched Virtual Circuit) and PVC (Permanent Virtual Circuit) user processes. 
Upper multiplexers are a specific application of standard STREAMS facilities 
that support multiple minor devices in a device driver. This figure also shows 
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Multiplexing 



that more complex configurations can be built by having one or more multi- 
plexed LAPB drivers below and multiple modules above the X.25 Packet Layer 
Protocol multiplexer diver. 

Developers can choose either upper or lower multiplexing, or both, when 
designing their applications. For example, a window multiplexer would have 
a similar configuration to the X.25 configuration of Figure 6-4, with a window 
driver replacing Packet Layer, a tty driver replacing LAPB, and the child 
processes of the terminal process replacing the user processes. Although the 
X.25 and window multiplexing Streams have similar configurations, their mul- 
tiplexer drivers would differ significantly. The IP multiplexer of Figure 6-2 has 
a different configuration than the X.25 multiplexer, and the driver would 
implement its own set of processing and routing requirements. 

In addition to upper and lower multiplexers, more complex configurations 
can be created by connecting Streams containing multiplexers to other multi- 
plexer drivers. With such a diversity of needs for multiplexers, it is not possi- 
ble to provide general purpose multiplexer drivers. Rather, STREAMS provides 
a general purpose multiplexing facility. The facility allows users to set up the 
inter-module/driver plumbing to create multiplexer configurations of generally 
unlimited interconnection. 

The connections are created from user space through specific STREAMS 
ioctl system calls. In a lower multiplexer, multiple Streams are connected 
below an application-specific, developer-implemented multiplexing driver. 
The multiplexing facility will only connect Streams to a driver. The ioctl call 
configures a multiplexer by connecting one Stream at a time below the opened 
multiplexer driver. As each Stream is connected to the driver, the connection 
setup procedure identifies the Stream to the driver. The driver will generally 
store this setup information in a private data structure for later use. 

Subsequently, when messages flow into the driver on the various con- 
nected Streams, the identity of the associated Stream is passed to the driver as 
part of the standard procedure call. The driver then has available the Stream 
identification, the previously stored setup information for this Stream, and any 
internal routing information contained in the message. These data are used, 
according to the application implemented, to process the incoming message 
and route the output to the appropriate outgoing Stream. 

Additionally, new Streams can be dynamically connected to a operating 
multiplexer without interfering with ongoing traffic, and existing Streams can 
be disconnected with similar ease. 
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STREAMS allows user processes to monitor and control Streams so that 
system resources (such as CPU cycles and process slots) can be used effec- 
tively. Monitoring is especially useful to user-level multiplexers, in v^hich a 
user process can create multiple Streams and switch messages among them 
(similar to STREAMS kernel-level multiplexing, described previously). 

User processes can efficiently monitor and control multiple Streams with 
two STREAMS system calls: poll and ioctl (used with the I_SETSIG command). 
These calls allow a user process to detect events that occur at the Stream head 
on one or more Streams, including receipt of a data or protocol message on 
the read queue and cessation of flow control. 

Synchronous monitoring is provided by use of poll alone; in this case, 
the user process cannot continue processing until after the system call com- 
pletes. When the calls are used together, they allow asynchronous, or con- 
current, operation of the process and STREAMS input/output. This allows the 
user process to monitor the Stream while carrying on other activities. 

To monitor Streams with poll, a user process issues that system call and 
specifies the Streams to be monitored, the events to look for, and the amount 
of time to wait for an event, poll will block the process until the time expires 
or until an event occurs. If an event occurs, poll will return the type of event 
and the Stream on which the event occurred. 

Instead of waiting for an event to occur, a user process may want to moni- 
tor one or more Streams while processing other data. It can do so by issuing 
the ioctl I_SETSIG command, specifying one or more Streams and events (as 
with poll). Unlike a poll, this ioctl does not force the user process to wait for 
the event but returns immediately and will issue a signal when an event 
occurs. The process must also request signal or sigset to catch the resulting 
SIGPOLL signal. 

If any selected event occurs on any of the selected Streams, STREAMS will 
cause the SIGPOLL catching function to be executed in all associated request- 
ing processes. However, the process(es) will not know which event occurred, 
nor on what Stream the event occurred. A process that issues the L_SETSIG 
can get more detailed information by issuing a poll after it detects the event. 
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Error and Trace Logging 

STREAMS includes error and trace loggers useful for debugging and 
administering modules and drivers. 

Any module or driver in any Stream can call the STREAMS logging func- 
tion strlog, (see log{7) in the User's/System Administrator's Reference Manual). 
When called, strlog will send formatted text to the error logger strerr, the 
trace logger strace, or both. The call parameters for strlog include the 
module/driver identification, a severity level, and the formatted text describ- 
ing the condition causing the call. The call also identifies the process (strerr 
and/or strace) to receive the resulting output message. 
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Figure 6-5: Error and Trace Logging 



strerr is intended to operate as a daemon process initiated at system 
startup. A call to strlog requesting an error to be logged causes an M_PROTO 
message to be sent to strerr, which formats the contents and places them in a 
daily file. The utility strdean is provided to periodically purge aged, unrefer- 
enced daily log files. 



OTHER FACILITIES 6-13 



Error and Trace Logging 



A call to strlog requesting trace information to be logged causes a similar 
M_PROTO message to be sent to strace, which places it in a user-designated 
file, strace is intended to be irutiated by a user. The user can designate the 
modules/drivers and severity level of the messages to be accepted for logging 
by strace. 

By using putmsg, a user process can submit its own M— PROTO messages 
to the log driver for inclusion in the logger of its choice. The messages must 
be in the same format required by the logging processes and will be switched 
to the logger(s) requested in the message. 

The output to the log files is formatted, ASCII text. The files can be pro- 
cessed by standard system commands such as grep or ed, or by developer- 
provided routines. 
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Introduction 



This chapter compares operational features of character I/O device drivers 
with STREAMS drivers and modules. It is intended for experienced developers 
of UNIX system character device drivers. Details are provided in the STREAMS 
Programmer's Guide. 



Environment 

No user environment is generally available to STREAMS module pro- 
cedures and drivers. The exception is the module and driver open and close 
routines, both of which have access to the u_area of the calling process and 
can sleep. Otherwise, a STREAMS driver, module put procedure, and module 
service procedure has no user context and can neither sleep nor access any 
u area. 

Multiple Streams can use a copy of the same module (that is, the same 
fmodsw), each containing the same processing procedures. This means that 
module code is re-entrant, so care must be exercised when using global data 
in a module. Put and service procedures are always passed the address of the 
QUEUE. For example, in Figure 2-5 Au calls Bu's put procedure with Bu as a 
parameter. The processing procedure establishes its environment solely from 
the QUEUE contents, typically the private data (for example, state information), 



Drivers 

At the interface to hardware devices, character I/O drivers have interrupt 
entry points; at the system interface, those same drivers generally have direct 
entry points (routines) to process open, close, read, write, and ioctl system 
calls. 

STREAMS device drivers have similar interrupt entry points at the 
hardware device interface and have direct entry points only for open and 
close system calls. These entry points are accessed via STREAMS, and the call 
formats differ from character device drivers. The put procedure is a driver's 
third entry point, but it is a message (not system) interface. The Stream head 
translates write and ioctl calls into messages and sends them downstream to 
be processed by the driver's write QUEUE put procedure, read is seen du-ectly 
only by the Stream head, which contains the functions required to process 
system calls. A driver does not know about system interfaces other than open 
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and close^ but it can detect absence of a read indirectly if flow control pro- 
pagates from the Stream head to the driver and affects the driver's ability to 
send messages upstream. 

For input processing, when the driver is ready to send data or other infor- 
mation to a user process, it does not wake up the process. It prepares a mes- 
sage and sends it to the read QUEUE of the appropriate (minor device) Stream. 
The driver's open routine generally stores the QUEUE address corresponding 
to this Stream. 

For output processing, the driver receives messages in place of a write 
call. If the message cannot be sent immediately to the hardware, it may be 
stored on the driver's write message queue. Subsequent output interrupts can 
remove messages from this queue. 

Drivers and modules can pass signals, error codes, and return values to 
processes via message types provided for that purpose. 

Modules 

As described above, modules have user context available only during the 
execution of their open and close routines. Otherwise, the QUEUES forming 
the module are not associated with the user process at the end of the Stream, 
nor with any other process. Because of this, QUEUE procedures must not 
sleep when they cannot proceed; instead, they must explicitly return control to 
the system. The system saves no state information for the QUEUE. The 
QUEUE must store this information internally if it is to proceed from the same 
point on a later entry. 

When a module or driver that requires private working storage (for exam- 
ple, for state information) is pushed, the open routine must obtain the storage 
from external sources. STREAMS copies the module template from fmodsw 
for the I_PUSH, so only fixed data can be contained in the module template. 
STREAMS has no automatic mechanism to allocate working storage to a 
module when it is opened. The sources for the storage typically include the 
STREAMS buffer pool or a module-specific kernel array that is installed when 
the system is configured. When using an array as a module storage pool, the 
maximum number of copies of the module that can exist at any one time must 
be determined. For drivers, this is tjrpically determined from the physical dev- 
ices connected, such as the number of ports on a multiplexer. However, cer- 
tain types of modules may not be associated with a particular external physi- 
cal limit. For example, the CANONICAL module shown in Figure 2-4 could 
be used on different types of Streams. 
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Glossary 



downstream 
driver 



message 



message queue 
message type 

module 



multiplexer 



pushable module 



The direction from Stream head to driver. 

The end of the Stream closest to a device. The princi- 
pal functions of the driver are handling any associated 
device, and transforming data and information 
between the device and Stream. It can also be a 
pseudo-driver, not directly associated with a device, 
which performs functions internal to a Stream, such as 
a multiplexer or log driver. 

One or more linked blocks of data or information, 
with associated STREAMS control structures containing 
a message type. Messages are the only means of 
transferring data and communicating within a Stream. 

A linked list of messages connected to a QUEUE. 

A defined set of values identifying the contents of a 
message. 

Software that performs functions on messages as they 
flow between Stream head and driver. A module is 
the STREAMS counterpart to the commands in a Shell 
pipeline, except that a module contains a pair of func- 
tions which allow independent bidirectional (down- 
stream and upstream) data flow and processing. 

A mechanism for connecting multiple Streams to a 
multiplexing driver. The mechanism supports the 
processing of interleaved data Streams and the pro- 
cessing of internetworking protocols. The multiplex- 
ing driver routes messages among the connected 
Streams. The other end of a Stream connected to a 
multiplexing driver is typically connected to a device 
driver. 

A module between the Stream head and driver. A 
driver is a non-pushable module and a Stream head 
includes a non-pushable module. 
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Glossary 

QUEUE 

read queue 
Stream 



Stream head 



STREAMS 



upstream 
write queue 



The set of structures that forms a module. A module 
is composed of two QUEUEs, a read (upstream) QUEUE 
and a write (downstream) QUEUE. 

The message queue in a module or driver containing 
messages moving upstream. It is associated with 
input data coming from a driver. 

The kernel aggregate created by connecting STREAMS 
components, resulting from an application of the 
STREAMS mechanism. The primary components are a 
Stream head, a driver and zero or more pushable 
modules between the Stream head and driver. A 
Stream forms a full-duplex processing and data- 
transfer path in the kernel, between a user process 
and a driver. A Stream is analogous to a Shell pipe- 
line, except that data flow and processing are bidirec- 
tional. 

The end of the Stream closest to the user process. 
The Stream head provides the interface between the 
Stream and the user process. The principal functions 
of the Stream head are processing STREAMS-related 
system calls and bidirectional transfer of data and 
information between a user process and messages in 
STREAMS' kernel space. 

A kernel mechanism that supports development of 
network services and data communication drivers. It 
defines interface standards for character input/output 
within the kernel, and between the kernel and user 
level. The STREAMS mechanism comprises integral 
functions, utility routines, kernel facilities and a set of 
structures. 

The direction from driver to Stream head. 

The message queue in a module or driver containing 
messages moving downstream. It is associated with 
output from a user process. 
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